{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# hvPlot.rgb\n",
    "\n",
    "```{eval-rst}\n",
    ".. currentmodule:: hvplot\n",
    "\n",
    ".. automethod:: hvPlot.rgb\n",
    "```\n",
    "\n",
    "## Backend-specific styling options\n",
    "\n",
    "```{eval-rst}\n",
    ".. backend-styling-options:: rgb\n",
    "```\n",
    "\n",
    "## Examples\n",
    "\n",
    "### Basic RGB plot\n",
    "\n",
    "This example demonstrates how to create a simple RGB image using synthetic data. Three 2D arrays representing the red, green, and blue color channels are stacked into a 3D [`xarray.DataArray`](inv:xarray#xarray.DataArray) and visualized using the `rgb` method. This `DataArray` is tailored to the default configuration of the `rgb` method: `band` as the first coordinate, `y` the second, and `x` the third. Set these keywords appropriately if your data is not structured this way."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import xarray as xr\n",
    "import hvplot.xarray\n",
    "\n",
    "colors = np.array([\n",
    "    [255,   0,   0],   # Red\n",
    "    [  0, 255,   0],   # Green\n",
    "    [  0,   0, 255],   # Blue\n",
    "], dtype=np.uint8)\n",
    "rgb_array = np.repeat(colors[:, np.newaxis, :], 2, axis=1)\n",
    "rgb_array = np.transpose(rgb_array, (2, 0, 1))\n",
    "da = xr.DataArray(\n",
    "    rgb_array,\n",
    "    dims=(\"band\", \"y\", \"x\"),\n",
    "    coords={\"band\": [\"R\", \"G\", \"B\"], \"y\": np.arange(3), \"x\": np.arange(2)},\n",
    ")\n",
    "print(da.coords)\n",
    "\n",
    "da.hvplot.rgb(aspect=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### From a PNG file"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example, the dataset is created by loading a PNG file into an `xarray.Dataset` object with [Pillow](https://python-pillow.github.io/). Note that in this case we need to set `x`, `y`, and `band` as the way the data is shaped does not match with hvPlot's default settings.\n",
    "\n",
    ":::{note}\n",
    "Since RGB images are stored starting at the top left pixel, we should start there when plotting to make sure that we get the picture in the correct orientation. This is done automatically when the y-coordinate values are *descending*. Otherwise, we need to set to [`flip_yaxis`](option-flip_yaxis) option to `True` to flip the y-axis.\n",
    ":::"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "\n",
    "ds = hvplot.sampledata.penguins_rgba(\"xarray\")\n",
    "print(ds)\n",
    "\n",
    "ds.hvplot.rgb(x=\"x\", y=\"y\", bands=\"channel\", flip_yaxis=True, aspect=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### From a GeoTIFF file\n",
    "\n",
    "The dataset used in the example below is derived from USGS Landsat 7 imagery and is created by loading a GeoTIFF file into an `xarray.Dataset` object with [rioxarray](https://corteva.github.io/rioxarray/). Note that we need to set `x` and `y` as the way the data is shaped does not match with the default's setting for these two keywords. Also, note that the `y` coordinates are *descending* so we do not need to set `flip_yaxis=True`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "\n",
    "ds = hvplot.sampledata.landsat_rgb(\"rioxarray\")\n",
    "print(ds)\n",
    "\n",
    "ds.hvplot.rgb(x=\"x\", y=\"y\", aspect=1, title=\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since this dataset contains geographic information, we can set the [`geo`](option-geo) and [`tiles`](option-tiles) options to `True` to overlay the image on web map tiles."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.xarray  # noqa\n",
    "\n",
    "ds = hvplot.sampledata.landsat_rgb(\"rioxarray\")\n",
    "print(ds.rio.crs)\n",
    "\n",
    "ds.hvplot.rgb(x=\"x\", y=\"y\", aspect=1, title=\"\", tiles=True, geo=True, padding=1)"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
